perf(locator): stop searching once the caller's matches are found - #5

Problem

Locator resolution collects every match before discarding all but the ones the caller asked for. resolve() calls resolve_all() and takes the first element; nth=N and first are applied as selection steps, after the search that produced the candidates has already finished walking the tree.

On a small tree that is invisible. On an application that materialises accessibility children on demand it dominates runtime, because the walk keeps asking the app to build elements long after the answer is known. Microsoft Word with a 74k-character document open, where AXLayoutArea reports kids=0 until something descends into it:

$ axcli --pid 704 snapshot --depth 4 --simplify
   ... 139.55s

The same traversal primitives are fine when they stop early — a depth-capped walk of the whole app costs 0.07s — so this is the search continuing past the point of usefulness rather than the AX tree being inherently slow.

It also makes failure slower than success: proving a locator ambiguous walked the entire tree to produce an exact count, so the error path cost more than the path that found an element.

Change

Each pipeline step now receives the number of candidates the steps after it can actually consume, computed backwards from what the caller requested.

Callers supply the final budget: resolve_one asks for two (one to act on, one to prove ambiguity), snapshot without --all asks for two (one to print, one to report that more exist), and locate_all asks for usize::MAX, which reproduces the previous behaviour exactly.

Three bounded variants were added alongside the existing functions rather than replacing them — find_limited, collect_matching_limited, resolve_locator_limited — each equal to its unbounded counterpart at usize::MAX.

Verification

Tested on macOS 27.0 (build 26A5388g, arm64), Word 16.111.3.

Word — a large document open, the pathological case

Finder — output equivalence

Ten locators covering each budget rule, comparing the old binary against the new one:

Finder: 9/10 byte-identical (stdout + stderr)

The tenth is the intended difference described below; its selected element and printed tree are identical.

cargo test passes (62 tests, 7 new) and cargo clippy reports 47 warnings both before and after, so no new ones.

One deliberate behaviour change

The ambiguity message now reports a lower bound:

- locator matched 8 elements, must be unique for actions
+ locator matched at least 2 elements, must be unique for actions

An exact total requires the full traversal this change exists to avoid, and it is a number the caller cannot act on — the suggested fix is >> nth=N either way. --all still reports the true count, because it genuinely collects every match.

Not addressed

A locator matching exactly one element is still slow on Word: proving there is no second match requires exhausting the tree. That is a traversal-order problem — DFS descends into the document subtree before reaching siblings such as the menu bar — and changing the order would change which element nth=N selects, so it is left out of this PR.